26장 Claude Code Action 자동화 (입문판)

출처: 클로드 코드 완벽 가이드, 코드팩토리 최지호

이 장에서 딱 3가지만 기억하세요. 1. 클로드 코드는 직접 대화하는 방식(인터렉티브)과 알아서 일하는 방식(헤드리스), 두 가지로 움직인다. 2. Claude Code Action은 깃허브에 상주하면서 PR과 이슈를 자동으로 처리하는 기능이다. 3. /install-github-app 명령 하나로 설치를 시작하고, 워크플로와 인증만 고르면 끝난다.

이 장은 빠르게 변하는 도구를 다룹니다. 요금·모델명·한도 같은 구체 수치는 원서/노트 기준 예시이며, 최신 값은 공식 문서에서 확인하세요.

학습 목표

이 장을 끝내면 다음을 할 수 있어요.

• 인터렉티브 모드와 헤드리스 모드의 차이를 구분한다.
• Claude Code Action이 무엇이고 어떻게 동작하는지 설명한다.
• /install-github-app 명령으로 설치 과정을 따라 한다.

26-0 들어가기 전에 — 잠깐, 이런 적 있죠?

밤늦게 코드를 짜서 깃허브에 PR(Pull Request, 내가 고친 코드를 합쳐달라고 보내는 요청. 마치 "이거 검토하고 본진에 넣어주세요" 하고 내는 결재 서류 같은 거예요)을 올렸어요.

그런데 리뷰해 줄 동료는 자고 있고, 내일 아침이나 되어야 봐줄 거예요.

급한 버그인데 검토를 못 받아서 며칠 멈춰 있던 적, 한 번쯤 있죠?

이렇게 "사람을 기다려야 해서 막히는" 순간을 없애주는 게 바로 이번 장의 주인공이에요.

깃허브 안에 24시간 일하는 AI 팀원을 한 명 들이는 거라고 생각하면 됩니다.

그 AI 팀원의 이름이 Claude Code Action이고요.

시작하기 전에 — 이 장 전에 알면 좋은 것

새 운동을 배우러 가면 "기초 체력 정도는 있어야 따라오기 편해요"라고 하잖아요.

이 장도 마찬가지예요.

아래 4가지를 어렴풋이라도 알고 있으면 훨씬 수월하게 읽힙니다.

몰라도 따라올 수는 있지만, 체크가 안 되는 항목은 잠깐 찾아보고 오면 좋아요.

자가점검 박스 — 마음속으로 체크해보세요.

• [ ] Git & GitHub 기본을 안다 (리포지터리·PR·이슈가 뭔지 설명할 수 있다)
• [ ] 클로드 코드를 터미널에서 써본 적이 있다 (명령을 직접 쳐봤다)
• [ ] GitHub Actions가 "깃허브의 자동화 기능"이라는 걸 안다
• [ ] API 키와 구독 모델이 다르다는 걸 안다 (종량제 vs 정액제)

용어 한 줄: 깃허브에서 어떤 일(예: PR 올리기)이 생기면 미리 정해둔 작업을 자동으로 돌려주는 기능을 깃허브 액션(GitHub Actions)이라고 불러요. (사무실에 "택배 오면 알아서 창고에 넣기" 규칙을 붙여둔 것과 비슷해요.)

체크가 안 된 항목이 있어도 괜찮아요.

이 장을 읽다 보면 자연스럽게 채워지도록 풀어서 설명할 거예요.

26-1 두 가지 실행 방식 — 인터렉티브 모드와 헤드리스 모드

이 절에서 딱 1가지만. 클로드 코드는 "직접 대화"와 "알아서 처리" 두 방식으로 일한다.

이렇게 하다 막힌 적 있죠?

평소에 우리는 터미널을 열고 클로드 코드에게 말을 겁니다.

"이 함수 고쳐줘" 하면 답이 오고, 또 물어보고, 또 답이 오고요.

이렇게 옆에 붙어서 대화하는 게 편할 때도 있지만, 매번 사람이 붙어 있어야 한다는 한계가 있어요.

자동으로 돌리고 싶은 작업, 예를 들어 "PR이 올라올 때마다 검토해줘" 같은 건 내가 계속 지켜볼 수 없잖아요.

그게 바로 두 방식이 나뉘는 이유예요.

그게 바로 인터렉티브 모드와 헤드리스 모드

• 인터렉티브 모드(Interactive Mode): 사용자와 직접 대화하며 터미널에서 실시간으로 작업하는 방식이에요. "주거니 받거니" 하는 모드입니다.
• 헤드리스 모드(Headless Mode): 화면 없이 백엔드에서 자동으로 실행되는 방식이에요. 배포나 자동화 작업에 주로 씁니다. "요청만 던지면 알아서 처리"하는 모드입니다.

여기서 "백엔드"는 사용자 눈에 보이는 화면 뒤에서 조용히 도는 부분을 뜻해요.

식당으로 치면 손님이 보는 홀이 아니라 주방 쪽이라고 생각하면 됩니다.

비유로 한눈에

회의는 그 자리에서 바로 묻고 답할 수 있지만, 내가 회의실에 있어야 하죠.

이메일은 보내놓고 다른 일을 해도 되지만, 답이 올 때까지 기다려야 하고요.

두 방식 각각의 장점이 다르다는 걸 느낌으로 잡으면 충분해요.

예시로 굳히기

예시 1 (일상 비유) — 인터렉티브는 전화 통화, 헤드리스는 음성 메시지 남기기예요. 전화는 바로 대화, 음성 메시지는 남겨두면 상대가 알아서 듣고 처리.

예시 2 (실제 장면) — 터미널에서 클로드 코드와 이렇게 주고받는 게 인터렉티브예요.

> 이 파일에 로그인 기능 추가해줘
(클로드가 코드 작성하고 보여줌)
> 좋아, 비밀번호 검증도 넣어줘
(클로드가 이어서 수정)

반면 헤드리스는 위처럼 화면에서 대화하지 않아요.

깃허브에 PR이 올라오면 사람이 안 봐도 알아서 검토가 시작되죠.

예시 3 (잘못된 예 vs 올바른 예)

잘못된 생각: "헤드리스 모드는 인터렉티브 모드보다 좋은 상위 버전이다."

올바른 생각: "둘은 용도가 다르다. 개발하며 탐색할 땐 인터렉티브, 자동화엔 헤드리스."

이럴 때 이렇게 — 내가 코드를 짜면서 이것저것 물어보고 싶다면 인터렉티브 모드, "PR마다 자동 검토" 같은 반복 작업이라면 헤드리스 모드를 떠올리세요.

26-2 Claude Code Action이란 무엇인가

이 절에서 딱 1가지만. Claude Code Action은 헤드리스 모드를 깃허브에 붙여 PR과 이슈를 자동 처리하는 기능이다.

이렇게 하다 막힌 적 있죠?

앞 절에서 본 헤드리스 모드, 좋긴 한데 "그래서 이걸 실제로 어디에 쓰지?" 싶죠.

매번 직접 명령을 안 쳐도 자동으로 돌아가면 좋을 텐데, 그 대표 사례가 바로 깃허브 연동이에요.

코드를 올리는 곳이 깃허브니까, 거기에 클로드 코드를 상주시키면 가장 쓸모가 많거든요.

그게 바로 Claude Code Action

Claude Code Action은 깃허브에서 클로드 코드를 직접 사용할 수 있게 해주는 기능이에요.

헤드리스 모드를 활용해서 깃허브에서 PR 리뷰, 버그 수정, 이슈 해결 등을 자동으로 수행합니다.

여기서 "이슈(Issue)"는 깃허브에서 "이런 버그가 있어요" "이 기능 추가해주세요" 하고 적어두는 할 일 카드 같은 거예요.

이게 동작하는 바탕에는 GitHub App이 있어요.

GitHub App은 깃허브에 설치해서 리포지터리에 기능을 추가하는 확장 앱이에요. 스마트폰에 앱을 깔아 기능을 늘리는 것과 같은 개념이죠.

여기서 "리포지터리(Repository)"는 프로젝트 코드를 통째로 담아두는 깃허브의 저장소 폴더라고 보면 됩니다.

비유로 한눈에

예시로 굳히기

예시 1 (일상 비유) — 회사에 새 팀원이 입사했다고 상상해 보세요. 이 팀원은 잠도 안 자고, PR이 올라올 때마다 즉시 검토하고, 부르면 버그도 고쳐줘요.

예시 2 (실제 장면) — 설치가 끝나면 PR을 올렸을 때 클로드 봇이 이런 식으로 자동 댓글을 답니다.

PR Review: Claude Code GitHub Workflow

Todo List:
- 워크플로 파일 읽고 분석
- 코드 품질과 모범 사례 검토
- 잠재적 버그나 문제 확인
- 성능 고려사항 점검
- 보안 우려사항 평가
- 건설적인 피드백 제공

예시 3 (잘못된 예 vs 올바른 예)

잘못된 이해: "클로드 코드 액션은 반드시 API 요금제가 있어야만 쓸 수 있다."

올바른 이해: "원래는 API 요금제만 지원했지만, 이제는 구독 플랜으로도 쓸 수 있다."

이럴 때 이렇게 — 비용을 예측 가능하게 관리하고 싶다면 구독 모델을, 사용량을 세밀하게 제어하고 싶다면 API 키를 떠올리세요. (둘의 차이는 26-3에서 설치하며 정리합니다.)

참고: 위 요금제/플랜 관련 내용은 원서/노트 기준 예시예요. 지원 방식이나 플랜은 바뀔 수 있으니, 최신 값은 공식 문서에서 확인하세요.

26-3 Claude Code Action 설치하기

이 절에서 딱 1가지만. /install-github-app 명령으로 시작해, 리포지터리·워크플로·인증을 차례로 고르면 설치가 끝난다.

이렇게 하다 막힌 적 있죠?

"좋아, 깃허브에 AI 팀원을 들이고 싶어. 근데 어디서부터 손대지?"

설정이 복잡할 것 같아서 망설인 적 있죠?

다행히 클로드 코드는 명령 하나로 설치 마법사를 띄워줘요.

화면이 시키는 대로 고르기만 하면 됩니다.

그게 바로 /install-github-app

/install-github-app은 클로드 코드 터미널에서 GitHub App 설치를 시작하는 슬래시 명령어예요.

"슬래시 명령어"는 앞에 /를 붙여 클로드 코드에게 특별한 기능을 실행시키는 단축 명령이에요. 채팅창에 /로 시작하는 단축 명령을 치는 것과 비슷하죠.

비유로 한눈에 — 설치 = 새 팀원 입사 절차

따라 하기 — 설치 8단계

아래는 안전한 기본 순서예요. 화면이 묻는 대로 따라가면 됩니다.

1단계: 클로드 코드에서 명령 실행
> /install-github-app

2단계: 리포지터리 선택
> Use current repository (현재 리포지터리 사용)
   또는 Enter a different repository (다른 리포지터리 입력)

3단계: 브라우저에서 GitHub App 설치
   https://github.com/apps/claude 에서 [Configure] 클릭

4단계: 클로드 코드로 돌아와 Enter

5단계: 워크플로 선택 (Space로 토글, Enter로 확정)
   @Claude Code — 이슈/PR에서 @claude 태그로 호출
   Claude Code Review — 새 PR마다 자동 리뷰

6단계: 인증 방식 선택
   Create a long-lived token (구독 토큰 만들기)
   또는 Enter a new API key (API 키 입력)

7단계: 클로드 홈페이지에서 [Authorize] 클릭

8단계: 자동 생성된 PR을 머지하면 설치 완료!

여기서 5단계에 나온 두 워크플로를 짚고 갈게요.

"워크플로(Workflow)"는 깃허브에서 자동으로 실행되는 작업 흐름을 적어둔 설정 파일이에요. "이런 일이 생기면 저렇게 자동으로 해라"라고 미리 적어둔 자동화 레시피라고 보면 됩니다.

• @Claude Code: 이슈나 PR 댓글에서 @claude를 태그하면 클로드가 응답하는 방식이에요. 필요할 때만 부르는 거죠.
• Claude Code Review: 새 PR이 생성될 때마다 자동으로 코드 리뷰를 수행하는 방식이에요.

8단계의 "머지(merge)"는 변경한 코드를 본진 코드에 합치는 것을 말해요.

인증 방식 두 가지 — API 키 vs 구독 모델

비용을 예측 가능하게 관리하고 싶다면 구독 모델을 추천해요.

세밀하게 사용량을 제어하거나 대량으로 쓸 거라면 API 키 방식이 맞고요.

참고: 위 인증/요금 관련 내용은 원서/노트 기준 예시예요. 실제 플랜과 과금 방식은 바뀔 수 있으니, 최신 값은 공식 문서에서 확인하세요.

예시로 굳히기

예시 1 (실제 장면) — 2단계에서 현재 리포지터리를 그대로 쓰면 이렇게 보일 수 있어요.

> Use current repository: codefactory-co/k-nomad

예시 2 (잘못된 예 vs 올바른 예)

잘못된 순서: 워크플로를 안 고르고 그냥 다음으로 넘어가 버림 → 자동 리뷰가 동작 안 함.

올바른 순서: 5단계에서 원하는 워크플로를 Space로 체크한 뒤 Enter로 확정.

이럴 때 이렇게 — "자동 리뷰가 안 돌아요"라는 상황이면, 5단계에서 Claude Code Review를 체크했는지부터 확인하세요.

한 걸음 더 ▸ 수동 설치 마법사 대신 직접 설정 파일로 설치하는 수동 방법도 있어요. 다만 입문 단계에선 위 /install-github-app 마법사면 충분합니다. 수동 설치가 필요하면 Claude Code Action 공식 저장소의 설치 안내를 확인하세요. (이 도구는 외부에서 빠르게 바뀌므로, 옵션과 명령은 공식 저장소에서 최신본을 확인하세요.)

26-4 설치 후 — 실전에서 어떻게 쓰나

이 절에서 딱 1가지만. 설치가 끝나면 PR엔 자동 리뷰가, 이슈엔 @claude 태그로 요청이 가능해진다.

이렇게 하다 막힌 적 있죠?

예전 방식으로 일하면 이런 흐름이었어요.

코드 작성 → PR 올림 → 리뷰어에게 요청 → 리뷰어가 바쁘면 대기 → 피드백까지 수시간에서 수일.

간단한 버그도 내가 직접 다 찾아야 했죠.

그게 바로 자동 리뷰 + @claude 호출

설치가 끝나면 흐름이 이렇게 바뀝니다.

코드 작성 → PR 올림 → 즉시 자동 코드 리뷰 시작 → 코드 품질, 버그, 보안, 성능을 한 번에 체크.

게다가 이슈에 @claude를 태그하면 버그 수정이나 기능 추가까지 요청할 수 있어요.

비유로 한눈에

예시로 굳히기

예시 1 (실제 장면) — 이슈 댓글에 이렇게 적으면 클로드가 작업을 시작해요.

@claude 로그인 버튼 클릭이 안 되는 버그 좀 고쳐줘

예시 2 (잘못된 예 vs 올바른 예)

잘못된 기대: "@claude만 달면 무조건 완벽하게 다 고쳐준다."

올바른 기대: "1차로 빠르게 처리해주는 보조 도구다. 결과는 사람이 확인하고 머지한다."

이럴 때 이렇게 — 자동 리뷰가 지적한 내용도, @claude가 고친 코드도, 머지 전에 한 번 사람이 훑어보는 습관을 들이세요.

도입 효과 정리

• PR 리뷰 대기 시간이 크게 줄어요 (즉시 리뷰).
• 코드 품질, 보안, 성능을 일관되게 검토받아요.
• 급한 버그나 이슈를 깃허브에서 바로 요청할 수 있어요.
• 사람은 더 창의적인 작업에 집중할 수 있어요.

26-5 정리 — 이 장에서 배운 것

• 클로드 코드는 직접 대화하는 인터렉티브 모드와, 알아서 처리하는 헤드리스 모드로 일한다.
• Claude Code Action은 헤드리스 모드를 깃허브에 붙여 PR과 이슈를 자동 처리하는 기능이다.
• /install-github-app 한 명령으로 설치를 시작하고, 리포지터리·워크플로·인증만 고르면 된다.
• 워크플로는 두 가지다. @Claude Code(불러야 옴)와 Claude Code Review(PR마다 자동).
• 인증은 두 가지다. 사용량 기반 API 키와 정액제 구독 모델.
• 설치 후엔 PR 자동 리뷰와 @claude 태그 요청으로 리뷰 대기 시간을 없앤다.

빠르게 변하는 도구이니, 요금·플랜·설치 옵션의 구체 값은 항상 공식 문서에서 최신본을 확인하세요.

연습문제

문제 1 — 두 모드 구분하기 (기본)

인터렉티브 모드와 헤드리스 모드의 차이를 설명하고, Claude Code Action이 어느 모드를 기반으로 하는지 말해보세요.

문제 2 — 두 워크플로 (기본)

설치 시 고를 수 있는 두 워크플로의 이름과 역할을 각각 설명해보세요.

문제 3 — 설치 절차 (기본)

/install-github-app 명령을 실행한 뒤, 설치를 마치기까지 거치는 큰 단계들을 순서대로 말해보세요.

문제 4 — 인증 방식 고르기 (중급)

비용을 예측 가능하게 관리하고 싶을 때 API 키와 구독 모델 중 어느 쪽이 유리한지, 그 이유와 함께 설명해보세요.

문제 5 — 실전 시나리오 (중급)

팀에 Claude Code Action을 도입하려 합니다. 설치 전 확인할 것, 워크플로 선택 전략, 도입 후 기대 효과를 각각 말해보세요.

부록 A — 용어 사전

부록 B — 비교표 모음

인터렉티브 모드 vs 헤드리스 모드

@Claude Code vs Claude Code Review

API 키 vs 구독 모델

위 표의 과금·플랜 내용은 원서/노트 기준 예시예요. 최신 값은 공식 문서에서 확인하세요.

부록 C — 참고 자료

이 장의 도구는 외부에서 빠르게 바뀝니다. 설치법·옵션·요금은 위 공식 자료에서 최신본을 확인하세요.

다음 장 예고: 다음 장에서는 또 다른 도구를 소개해요. 지금 몰라도 됩니다.